Introduction

This documentation contains the instructions for integrating Apple Pay on the Web using the Moneris Gateway. It contains specifications for transaction requests and responses.

System and Skill Requirements

1. Safari browser on compatible Apple devices only
2. Knowledge of Javascript

Getting Started With Apple Pay

In order to integrate your Apple Pay on the Web payment solution, there are a few basic tasks you have to do to begin:

1. Boarding your Apple Pay credentials with Moneris
2. Integrating your website's payment page with Apple Pay on the Web
3. Customizing your project's code to work with the Moneris Gateway

Onboarding on the Web

To board your credentials for an Apple Pay on the Web solution, there are ten basic initial steps:

1. Registering an Apple merchant ID at the Apple Developer Portal
2. Downloading a CSR file from the Moneris Merchant Resource Center
3. Uploading the CSR file to Apple
4. Downloading a signed Apple Pay Payment Processing Certificate from Apple
5. Uploading the signed Apple Pay Payment Processing Certificate to the Merchant Resource Center
6. Downloading a Client CSR file from the Moneris Merchant Resource Center
7. Uploading the Client CSR file to the Apple Developer Portal
8. Registering a payment processing domain with Apple
9. Downloading an Apple Pay Merchant Identity Certificate
10. Uploading the Apple Pay Merchant Identity Certificate (Client Certificate) to the Merchant Resource Center

1. Registering an Apple Merchant ID

The first required step for the boarding process for your Apple Pay In-App is to get a Apple merchant ID on the Apple Developer Portal at developer.apple.com.

2. Downloading a CSR from Merchant Resource Center

Use your Apple merchant ID, also referred to as your Vendor ID, to obtain a client signing certificate (CSR) from the Moneris Merchant Resource Center.

To download your CSR from the Merchant Resource Center:

1. Go the Moneris Merchant Resource Center at one of the following URLs, depending on your stage of development:
   
   Testing/QA: https://esqa.moneris.com/mpg
   Production: https://www3.moneris.com/mpg
   
   
2. On the navigation bar at the top, select Admin > Apple Pay
3. In the fields under the Download CSR section, enter your Apple merchant ID and an email address as a point of contact
4. Click Download CSR to get the certification signing request (CSR) file from Moneris

3. Uploading the CSR to Apple

Once you have downloaded the CSR from the Moneris Merchant Resource Center, you upload it to the Apple Developer Portal at developer.apple.com.

The CSR from Moneris is required before Apple will issue you a Apple Pay payment processing certificate in the next step.

NOTE: This procedure or some of its details may change at the discretion of Apple, please refer to the Apple Developer Portal for the most up-to-date information.

To upload the CSR to the Apple Developer Portal:

1. In the Apple Developer Portal, go to Identifiers > Merchant IDs
2. Under the Apple Pay Payment Processing Certificate section click Create Certificate
3. Click Continue
4. In the Generate your certificate step, choose the CSR file from its location and click Upload

4. Downloading a Signed Apple Pay Payment Processing Certificate

After you have uploaded your Moneris Payment Processing CSR to the Apple Developer Portal, Apple gives you the option to download the signed Apple Pay payment processing certificate.

NOTE: This procedure or some of its details may change at the discretion of Apple, please refer to the Apple Developer Portal for the most up-to-date information.

To download the signed Apple Pay payment processing certificate, click Download and save it to your device.

5. Uploading the Signed Certificate to MRC

Once you have the signed Apple Pay Payment Processing Certificate, you upload it to the Merchant Resource Center in order to complete the boarding process for the Apple Pay In-App solution.

To upload the signed Apple Pay Payment Processing Certificate to the Merchant Resource Center:

1. Select Admin > Apple Pay in the Merchant Resource Center
2. Under the heading Apple Merchant Certificates, find the row with your Vendor ID (i.e., the Apple merchant ID)
3. Click the Upload Apple Signed Certificate button in that row
4. Choose the certificate from its location on your device to upload it.

6. Downloading a Merchant Identity CSR from MRC

The next step in the Apple Pay on the Web boarding process is to download a Client CSR from the Moneris Merchant Resource Center.

To download a Client CSR:

1. In the Merchant Resource Center, go to Admin > Apple Pay
2. Under the Apple Merchant Certificates section, find the row that contains your Vendor ID (Apple Merchant ID)
3. Click Client Certificates
4. In the email field, enter your email address as a point of contact
5. In the Domain field, add the domain that you will register for processing with Apple
6. Click Download Client CSR and save the Client CSR file to your device

7. Uploading a Client CSR to Apple

To obtain an Apple Pay Merchant Identity Certificate for your Apple Pay on the Web solution, you upload the Moneris Client CSR that you downloaded from the Merchant Resource Center.

8. Registering your domain with Apple

The Apple Pay on the Web solution requires you to register with Apple each web domain where you will be performing Apple Pay transactions.

NOTE: This procedure or some of its details may change at the discretion of Apple, please refer to the Apple Developer Portal for the most up-to-date information.

To register your domain with Apple:

1. Go to the Apple Developer Portal and select your merchant ID
2. Click Edit
3. Under Merchant Domains in the Apple Pay Payment Processing on the Web section, click Add Domain

9. Downloading a Apple Pay Merchant Identity Certificate

The Apple Pay Merchant Identity Certificate is referred to in the Moneris Merchant Resource Center as the Client Certificate.

To download the Apple Pay Merchant Identity Certificate:

1. Go to the Apple Developer Portal and select your merchant ID
2. Click Edit
3. Under Apple Pay Merchant Identify Certificate, click Download

10. Uploading Apple Pay Merchant Identity Certificate

Once you have downloaded your Apple Pay Merchant Identity Certificate, the final step is to upload that certificate to the Moneris Merchant Resource Center, where it is referred to as a "Client Certificate".

To upload the Apple Merchant Identity Certificate (Client Certificate) to the MRC:

1. In the Merchant Resource Center, go to Admin > Apple Pay
2. Under the Apple Merchant Certificates section, find the row containing your merchant ID (Vendor ID)
3. Click Client Certificate
4. In the Apple Client Certificate section of the new page, find the row listed for your domain
5. Click Upload Apple Signed Certificate to upload the Apple Merchant Identity Certificate file on your device to the MRC

Developing an Apple Pay Payment Page

In order to test the functionality of your Apple Pay solution with the Moneris Gateway, you first need a demo payment page.

Apple provides some examples for Apple Pay on the Web on the Apple developer portal for developers to use in integrating their Apple Pay solutions.

For an example of a Apple Pay on the Web demo payment page example:

https://applepaydemo.apple.com/

Integrating Your Website – Apple Pay on the Web

To integrate your website's payment page with Apple Pay on the Web via the Moneris Gateway, do the following:

1. Configure your back-end server to send a Preload request to Moneris Gateway in order to get a unique ticket number for each transaction; for more info on Preload requests, see Preload Request section

2. On your payment page, add the following code in the head section:

   Testing/QA

   <script type="text/javascript" src="https://esqa.moneris.com/applepayjs/applepay-api.js"></script>

   Production

   <script type="text/javascript" src="https://www3.moneris.com/applepayjs/applepay-api.js"></script>

3. In the body of your payment page, insert the following <div> to enable the library to communicate:

   <div id="moneris-apple-pay" store-id="store 1" merchant-identifier="yourunique-merchant-identifier" display-name="your-display-name"></div>

   Please referred to the User Guide to register your domain and obtain your Apple Pay Simple Web Setup Merchant identifier. Please note that the Simple Web setup merchant identifier would be prefixed with simple.moneris.YourUniqueDomainName.

4. Using the ticket obtained within the preload, use the setTicket() to process an Apple Pay transaction. This step mandatory for the Simple Web setup and must be set before the session.onvalidatemerchant function.

   //Obtain the ticket from preload request should be done in backend, not in browser.

   window.MonerisApplePay.setTicket("");

5. Create the Apple Pay session and its event handlers to validate the applepay session and process payment, configure the code so it looks like the following:

   session = new ApplePaySession(3, request); 
   session.onvalidatemerchant = (event) => { 
      console.log("Validate merchant"); 
      const validationURL = event.validationURL; 
      window.MonerisApplePay.validateSession(validationURL, apSessionValidationSuccess, apSessionValidationError); 
   }; 
   
   session.onpaymentauthorized = (event) => { 
      // Send payment for processing... 
      const payment = event.payment; 
      const paymentJson = JSON.stringify(payment); 
      const respDiv = document.getElementById("apple-pay-resp"); 
      const uiDiv = document.getElementById("apple-pay-ui"); 
   
      uiDiv.classList.add("none"); 
   
      respDiv.innerText = "Processing Payment...Please wait"; 
   
      var moneris_request = { 
         payment:event.payment 
      } 
   
      var transType = "preauth"; 
      if (typeof(window.MonerisApplePay[transType]) === "function") {  
         window.MonerisApplePay[transType](moneris_request, function(receipt) { 
            //make call to your backend to check async response 
            console.log(receipt); 
            if (receipt.receipt.ResponseCode  
               && !isNaN(receipt.receipt.ResponseCode)  
               && parseInt(receipt.receipt.ResponseCode) < 50){  
            
               session.completePayment(ApplePaySession.STATUS_SUCCESS); 
            } else {  
               session.completePayment(ApplePaySession.STATUS_FAILURE); 
            }  
            respDiv.innerText = "" + JSON.stringify(receipt); 
         }); 
      } 
   } 
   
   function apSessionValidationSuccess(response) { 
      console.log(response); 
      session.completeMerchantValidation(response); 
   } 
   
   function apSessionValidationError(response) { 
      console.log("Failed to validate merchant session"); 
      console.log(response); 
   } 
   
   session.begin();

Transaction Types

Moneris Gateway Apple Pay SDK supports the following transactions:

• Apple Pay Purchase
• Apple Pay Pre-Authorization

Once you have processed the initial transaction using Apple Pay Purchase or Apple Pay Pre-Authorization, you can use the Moneris Gateway Unified API or Batch Upload solution to process one of the following supplemental transactions:

• Refund
• Purchase Correction (not applicable to INTERAC® e-Commerce transactions)
• Pre-Authorization Completion

NOTE: INTERAC® e-Commerce transaction functionality is currently available only when processing a Purchase transaction.

In addition, the Moneris Gateway Apple Pay SDK also supports optional features, such as Customer Information and recurring transactions.

Preload Request

Requests a unique ticket number from the Moneris Gateway server, which responds with the ticket number to your back-end server at the URL provided.

The Preload request is sent prior to sending a financial transaction in Apple Pay on the Web and Google Pay™ Web.

If no response is received within 15 seconds, the request will time out.

Preload transaction request URL for Moneris Gateway

Testing: https://esqa.moneris.com/gateway2/servlet/MpgRequest

Production: https://www3.moneris.com/gateway2/servlet/MpgRequest

Preload transaction request object

Connection fields – Required

Preload transaction request fields – Required

<?xml version="1.0" encoding="UTF-8"?>
<request>
   <store_id>your_storeId</store_id>
   <api_token>your_apiToken</api_token>
   <applepay_preload>
      <order_id>example_orderId</order_id>
      <amount>1.00</amount>
      <receipt_url>https://example.com/example.php</receipt_url>
   </applepay_preload>
</request>

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <receipt>
      <PreloadTicket>ap1575405989TfehNuPgCwi3BBNEXN</PreloadTicket>
      <Message>Preload request successfully registered</Message>
      <ResponseCode>001</ResponseCode>
   </receipt>
</response>

Apple Pay Token Purchase

The Apple Pay Token Purchase transaction verifies funds on the customer’s card, removes the funds and readies them for deposit into the merchant’s account.

Required transaction objects – Apple Pay Token Purchase

Apple Pay Token Pre-Authorization

The Apple Pay Token Pre-Authorization verifies and locks funds on the customer’s credit card. The funds are locked for a specified amount of time, based on the card issuer. A subsequent Pre-Authorization Completion transaction must be performed for the funds to settle into the merchant’s account.

This transaction can only be performed on a credit card.

Required transaction objects – Apple Pay Token Pre-Authorization

Testing your Solution

For testing your Apple Pay In-App solution, you will need to:

1. Complete the onboarding process
2. Get a unique test Store ID
3. Get Apple merchant ID
4. Configure code on your payment page

Getting a Unique Test Store ID

For testing purposes, you can either use the pre-existing test stores or you can create your own unique test store where you will only see your own transactions.

To get your unique Store ID for testing:

1. Log in to the Developer Portal
2. In the My Profile dialog, click the Full Profile button
3. Under My Testing Credentials, select Request Testing Credentials
4. Enter your Developer Portal password and select your country
5. Record the Store ID that are given, as you will need them for logging in to the Merchant Resource Center (Store ID).

Alternatively, you can use the pre-existing test stores already set up in the Merchant Resource Center as described in the following section

Test Store Credentials

For testing purposes, you can either use the pre-existing test stores or you can create your own unique test store where you will only see your own transactions. If you want to use pre-existing stores, use the test credentials provided in the following table.

Configuring your Payment Page for Testing

To configure your payment page in your Apple Pay on the Web solution for testing:

1. On your payment page, change the script tag's src attribute to link to the test library location:

   <script type="text/javascript" src="https://esqa.moneris.com/applepayjs/applepay-api.js"></script>

2. In the body of your payment page, change the div tag's store-id and merchant-identifier attributes to reflect your test Store ID and Apple merchant ID:

   <div id="moneris-apple-pay" store-id="store 1" merchant-identifier="your-unique-QA-merchant-identifier"></div>

Moving to Production

To move your Apple Pay on the Web solution into production you need to:

1. Complete the onboarding process
2. Get production Store ID
3. Get Apple merchant ID
4. Configure code in the index.html file

NOTE: For each transaction that is processed, you should verify the payment amount to ensure that all data passed to Moneris in the request was correct. For more information, see Verifying Your Transactions section.

Getting a Production Store ID

In production, you use the Store ID that was given in your activation letter from Moneris.

Configuring Your Payment Page for Production

To configure your payment page in your Apple Pay on the Web solution for production:

1. In your payment page code, change the script tag's src attribute to link to the production library location:

   <script type="text/javascript" src="https://www3.moneris.com/applepayjs/applepay-api.js"></script>

2. In the body of your payment page, change the div tag's store-id and merchant-identifier attributes to reflect your production Store ID and production Apple merchant ID:

   <div id="moneris-apple-pay" store-id="store 1" merchant-identifier="your-unique-production-merchant-identifier"></div>

Verifying your Transactions

When you send a Preload transaction, you must include a transaction amount and a receipt URL, hosted on your back-end server. The Moneris Gateway sends the transaction response to your receipt URL so that you can verify the amount you sent in the transaction request matches the one coming back in the response from the Moneris Gateway.

As a secondary check, you can also manually look at your transactions in the Moneris Merchant Resource Center.

To use the Merchant Resource Center to verify your transactions have processed:

1. Log in to the Merchant Resource Center at https://esqa.moneris.com/mpg (testing) or https://www3.moneris.com/mpg (production)
2. Find your transactions under Reports > Transactions

Request Fields

Mandatory Request Fields

Optional CustInfo Request Fields

The customer information section is optional, but if included, all of the fields below are mandatory and must be populated, though they can be populated with a blank value.

Shipping Information

Optional Recurring Billing Fields

The recurring billing section is optional, but if included, all of the fields below are mandatory and must be populated.

Response Fields

Error Messages

Error messages that are returned if the gateway is unreachable

Global Error Receipt – You are not connecting to our servers.  This can be caused by a firewall or your internet connection.  

Response Code = NULL – The response code can be returned as null for a variety of reasons.   A majority of the time the explanation is contained within the Message field.   When a ‘NULL’ response is returned it can indicate that the Issuer, the credit card host, or the gateway is unavailable, either because they are offline or you are unable to connect to the internet.  A ‘NULL’ can also be returned when a transaction message is improperly formatted.

Error messages that are returned in the Message field of the response

Message: XML Parse Error in Request: <System specific detail>
Cause: For some reason an improper XML document was sent from the API to the servlet

Message: XML Parse Error in Response: <System specific detail>
Cause: For some reason an improper XML document was sent back from the servlet

Message: Transaction Not Completed Timed Out
Cause: Transaction times out before the host responds to the gateway

Message: Request was not allowed at this time
Cause: The host is disconnected

Message: Could not establish connection with the gateway: <System specific detail>
Cause: Gateway is not accepting transactions or server does not have proper access to internet

Message: Input/Output Error: <System specific detail>
Cause: Servlet is not running

Message: The transaction was not sent to the host because of a duplicate order id
Cause: Tried to use an order id which was already in use

Message: The transaction was not sent to the host because of a duplicate order id
Cause: Expiry Date was sent in the wrong format

Vault error messages

Message: Can not find previous
Cause: Data key provided was not found in our records or profile is no longer active.

Message: Invalid Transaction
Cause: Transaction cannot be performed because improper data was sent or
Mandatory field is missing or an invalid SEC code was sent.